ShowTable of Contents
In the Notes/Domino 8.5.2 release,
CKEditor has been integrated into XPages and it is now used as the default rendering for the XPages Rich Text Control. CKEditor is a WYSIWYG editor and it provides a wide range of features for creating and editing rich text content. As well as the basic styling options for text, it is also possible to add tables, links and emoticons to your rich text content. CKEditor has also been enhanced within XPages to allow you to embed images directly within your Domino documents.
CKEditor 3.2.1.6 is included in both the Notes Client and the Domino server in the 8.5.2 release. The install files can be found in <Notes data dir>/domino/html/ckeditor and <Domino data dir>/domino/html/ckeditor respectively.
This document will highlight some of the main features of the editor and discuss how it can be configured in different ways to suit your needs.
CKEditor Features
Firstly, the editor comes with 3 predefined toolbars -
Slim,
Medium and
Large as shown in Figure 1. These toolbars provide varying levels of functionality which may be useful in different scenarios e.g full document editing, blog posts, comments etc.
Figure 1: 3 Available Toolbars for CKEditor in XPages
The
Medium toolbar is used by default in XPages but you can easily configure the Rich Text Control to use either the
Slim or
Large toolbars as follows:
In Domino Designer, select the Rich Text Control in the Design View. Click the
Dojo tab on the Properties panel and add a Dojo attribute named
toolbarType with a value of
Slim,
Medium (default), or
Large as shown in Figure 2.
Figure 2: Configuring the ToolbarType for CKEditor in XPages
CKEditor includes many features that are new to XPages in 8.5.2. Table 1 highlights some of these.
Table 1: Rich Text Editing Features New to XPages in 8.5.2
| Icon | Title | Description |
| Maximize | Allows you to expand the editor area to the full browser window. This is particularly useful when creating and editing large documents. |
| Link | Provides a 'URL Link' dialog which allows you to Insert URLs into the document body. You can also provide alternative text to display within the document and specify whether the link should open in a new window or not. |
| Insert Image | Provides a dialog which allows you to browse your file system to select the image you wish to insert into your document. Alternatively you can enter a URL to a remote image on the 'Image Information' tab. |
| Insert Table | Provides a dialog which allows you to insert a table into the document. You can specify various table properties such as number of rows, number of columns, width, height etc. |
| Insert Emoticons | Provides a dialog which provides a number of emoticons which you can select to insert into your document. |
| Paste | Provides a range of pasting options including 'Paste' which provides Ctrl+v paste functionality, 'Paste as plain text' which removes formatting from the pasted content, 'Paste Special' which supports pasting of rich text content from desktop editing programs that copy HTML content to the clipboard and 'Paste Notes Document Link' which allows you to paste a document link from Notes into the CKEditor. |
Configuring CKEditor
You will notice from the discussion above that Dojo properties are used to configure the toolbar options for CKEditor. While CKEditor is a separate JavaScript component to Dojo, CKEditor has been integrated into XPages through a Dojo Wrapper. This means that the CKEditor effectively acts as a Dojo widget within your XPages. This implementation allows reuse of mechanisms that were already in place for passing attributes through to the widget, supporting events, partial update etc. In fact, the
dojoAttributes property of the Rich Text Control primarily maps to the CKEDITOR.config properties as specified in the
CKEditor API. This means that CKEditor can be configured in a number of different ways within your XPages applications.
For example, instead of using the predefined toolbars mentioned earlier, you can also define your own toolbar for CKEditor. To define your own toolbar, add a Dojo attribute to the Rich Text Control called
toolbar. Compute the value for this attribute in Server Side JavaScript and enter an array containing the toolbar options you want to make available. For example, the following value will result in the toolbar displayed in Figure 3.
var myToolbar = "[['Font','FontSize'], \n"
+"['Preview', 'Bold','TextColor','BGColor'], \n"
+"['Italic','Underline','Strike','-','Subscript','Superscript']]";
return myToolbar;
Figure 3: User Defined CKEditor Toolbar in XPages
The CKEditor install in Notes/Domino 8.5.2 does provide some extra plugins that are not available in any of the default toolbars in XPages. You can enable these extra plugins through the
toolbar Dojo attribute as described above, however please note that they are not officially supported in XPages. For example, in the usecase above, the 'preview' plugin is enabled, therefore we can add 'Preview' to the toolbar. Other additional plugins provided by CKEditor include 'templates' (toolbar option: 'Templates') which allows you to define HTML templates for rich text documents, 'selection' (toolbar option: 'SelectAll') which allows you to provide a 'Select All' feature and 'print' (toolbar option: 'Print') which allows users to print the document from directly within the editor,
If you do wish to use any of these additional plugins, you first need to make sure that the plugin is loaded. You can inspect the config.plugins property of your CKEditor instance in the DOM to see what plugins are available (using Firebug for example). If the plugin you require is not loaded, you can load it using the
extraPlugins Dojo attribute
. Add a Dojo attribute to the Rich Text Control called
extraPlugins. The value of this should be a comma separated list of any extra plugins you wish to load.
Examples of other configuration options you can set on CKEditor include
language which defines the user interface language to use,
contentsLangDirection which defines the direction in which the text is entered into the editor area and
enterMode which defines the behaviour of the enter key. Figure 4 shows a sample Rich Text Control in Domino Designer which have these properties set.
Figure 4: CKEditor Configuration Options in XPages
In addition, CKEditor in Notes/Domino 8.5.2 comes with 3 available skins specified in <Notes or Domino data dir>/domino/html/ckeditor/skins. XPages supports the
lotus skin. The other 2 skins are included as samples and may not be maintained or available in future CKEditor releases. If you would like to create your own skin, you can do so by defining it in the same format as the ones provided. See documentation on
CKEditor Skins for further details on this.
You can then apply your new skin to CKEditor in XPages by adding a
skin Dojo attribute. Note - there is currently an open issue in CKEditor which requires all skins to be in the <Notes or Domino install directory>/data/domino/html/ckeditor/skins directory. This issue has been reported and it should be possible to use custom paths for skins in future releases.
Full details on the CKEditor.config properties and their possible values are available in the
CKEditor API.